Mapping an EISA Device Into Memory

Mapping an EISA Device Into Memory

As discussed in "Device Addresses", an I/O device is represented as an address or range of addresses in the physical address space. A kernel-level device driver has the ability to set up a mapping between the physical address of a device register and an arbitrary location in the address space of a user-level process. When this has been done, the device register appears to be a variable in memory--the program can assign values to it, or refer to it in expressions.

Learning EISA Device Addresses

In order to map an EISA device for PIO, you must know the following points:

which EISA bus adapter the device is on
In all present Silicon Graphics systems, there is only one EISA bus adapter, and its number is 0.
whether you need access to the EISA bus memory or I/O address space
the address and length of the desired registers within the address space

You can find all these values by examining files in the /var/sysgen/system directory, especially the /var/sysgen/system/irix.sm file, in which each configured EISA device is specified by a VECTOR line. When you examine a VECTOR line, note the following parameter values:

bustype Specified as EISA for EISA devices. The VECTOR statement can be used for other types of buses as well.
adapter The number of the bus where the device is attached (0).
iospace, iospace2, iospace3 Each iospace group specifies the address space, starting bus address, and the size of a segment of bus address space used by this device.

Within each iospace parameter group you find keywords and numbers for the address space and addresses for a device. The following is an example of a VECTOR line (which must be a single physical line in the system file):

VECTOR: bustype=EISA module=if_ec3 ctlr=1
iospace=(EISAIO,0x1000,0x1000)
exprobe_space=(r,EISAIO, 0x1c80,4,0x6010d425,0xffffffff)

This example specifies a device that resides in the I/O space at offset 0x1000 (the slot-1 I/O space) for the usual length of 0x1000 bytes. The exprobe_space parameter suggests that a key device register is at 0x1c80.

Opening a Device Special File

When you know the device addresses, you can open a device special file that represents the correct range of addresses. The device special files for EISA mapping are found in /dev/eisa.

The naming convention for these files is as follows: Each file is named eisaBaM, where

B is a digit for the bus number (0)
M is the modifier, either io or mem

The device special file for the device described by the example VECTOR line in the preceding section would be /dev/vme/eisa0aio.

In order to map a device on a particular bus and address space, you must open the corresponding file in /dev/eisa.

Using the mmap() Function

When you have successfully opened the device special file, you use the file descriptor as the primary input parameter in a call to the mmap() system function.

This function is documented for all its many uses in the mmap(2) reference page. For purposes of mapping EISA devices, the parameters should be as follows (using the names from the reference page):

addr Should be NULL to permit the kernel to choose an address in user process space.
len The length of the span of bus addresses, as documented in the iospace group in the VECTOR line.
prot PROT_READ, or PROT_WRITE, or the logical sum of those names when the device is used for both input and output.
flags MAP_SHARED, with the addition of MAP_PRIVATE if this mapping is not to be visible to child processes created with the sproc() function (see the sproc(2) reference page).
fd The file descriptor from opening the device special file in /dev/eisa.
off The starting bus address, as documented in the iospace group in the VECTOR line.

The value returned by mmap() is the virtual memory address that corresponds to the starting bus address. When the process accesses that address, the access is implemented by data transfer to the EISA bus.

Note: When programming EISA PIO, you must always be aware that EISA devices generally store 16-bit and 32-bit values in "small-endian" order, with the least-significant byte at the lowest address. This is opposite to the order used by the MIPS CPU under IRIX. If you simply assign to a C unsigned integer from a 32-bit EISA register, the value will appear to be byte-inverted.

bustype	Specified as EISA for EISA devices. The VECTOR statement can be used for other types of buses as well.
adapter	The number of the bus where the device is attached (0).
iospace, iospace2, iospace3	Each iospace group specifies the address space, starting bus address, and the size of a segment of bus address space used by this device.

B	is a digit for the bus number (0)
M	is the modifier, either io or mem

addr	Should be NULL to permit the kernel to choose an address in user process space.
len	The length of the span of bus addresses, as documented in the iospace group in the VECTOR line.
prot	PROT_READ, or PROT_WRITE, or the logical sum of those names when the device is used for both input and output.
flags	MAP_SHARED, with the addition of MAP_PRIVATE if this mapping is not to be visible to child processes created with the sproc() function (see the sproc(2) reference page).
fd	The file descriptor from opening the device special file in /dev/eisa.
off	The starting bus address, as documented in the iospace group in the VECTOR line.